home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dgeesx.z / dgeesx
Encoding:
Text File  |  2002-10-03  |  9.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGEESX - compute for an N-by-N real nonsymmetric matrix A, the
  10.      eigenvalues, the real Schur form T, and, optionally, the matrix of Schur
  11.      vectors Z
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE DGEESX( JOBVS, SORT, SELECT, SENSE, N, A, LDA, SDIM, WR, WI,
  15.                         VS, LDVS, RCONDE, RCONDV, WORK, LWORK, IWORK, LIWORK,
  16.                         BWORK, INFO )
  17.  
  18.          CHARACTER      JOBVS, SENSE, SORT
  19.  
  20.          INTEGER        INFO, LDA, LDVS, LIWORK, LWORK, N, SDIM
  21.  
  22.          DOUBLE         PRECISION RCONDE, RCONDV
  23.  
  24.          LOGICAL        BWORK( * )
  25.  
  26.          INTEGER        IWORK( * )
  27.  
  28.          DOUBLE         PRECISION A( LDA, * ), VS( LDVS, * ), WI( * ), WORK( *
  29.                         ), WR( * )
  30.  
  31.          LOGICAL        SELECT
  32.  
  33.          EXTERNAL       SELECT
  34.  
  35. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  36.      These routines are part of the SCSL Scientific Library and can be loaded
  37.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  38.      directs the linker to use the multi-processor version of the library.
  39.  
  40.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  41.      4 bytes (32 bits). Another version of SCSL is available in which integers
  42.      are 8 bytes (64 bits).  This version allows the user access to larger
  43.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  44.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  45.      only one of the two versions; 4-byte integer and 8-byte integer library
  46.      calls cannot be mixed.
  47.  
  48. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  49.      DGEESX computes for an N-by-N real nonsymmetric matrix A, the
  50.      eigenvalues, the real Schur form T, and, optionally, the matrix of Schur
  51.      vectors Z. This gives the Schur factorization A = Z*T*(Z**T). Optionally,
  52.      it also orders the eigenvalues on the diagonal of the real Schur form so
  53.      that selected eigenvalues are at the top left; computes a reciprocal
  54.      condition number for the average of the selected eigenvalues (RCONDE);
  55.      and computes a reciprocal condition number for the right invariant
  56.      subspace corresponding to the selected eigenvalues (RCONDV).  The leading
  57.      columns of Z form an orthonormal basis for this invariant subspace.
  58.  
  59.      For further explanation of the reciprocal condition numbers RCONDE and
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      RCONDV, see Section 4.10 of the LAPACK Users' Guide (where these
  75.      quantities are called s and sep respectively).
  76.  
  77.      A real matrix is in real Schur form if it is upper quasi-triangular with
  78.      1-by-1 and 2-by-2 blocks. 2-by-2 blocks will be standardized in the form
  79.                [  a  b  ]
  80.                [  c  a  ]
  81.  
  82.      where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc).
  83.  
  84.  
  85. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  86.      JOBVS   (input) CHARACTER*1
  87.              = 'N': Schur vectors are not computed;
  88.              = 'V': Schur vectors are computed.
  89.  
  90.      SORT    (input) CHARACTER*1
  91.              Specifies whether or not to order the eigenvalues on the diagonal
  92.              of the Schur form.  = 'N': Eigenvalues are not ordered;
  93.              = 'S': Eigenvalues are ordered (see SELECT).
  94.  
  95.      SELECT  (input) LOGICAL FUNCTION of two DOUBLE PRECISION arguments
  96.              SELECT must be declared EXTERNAL in the calling subroutine.  If
  97.              SORT = 'S', SELECT is used to select eigenvalues to sort to the
  98.              top left of the Schur form.  If SORT = 'N', SELECT is not
  99.              referenced.  An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if
  100.              SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex
  101.              conjugate pair of eigenvalues is selected, then both are.  Note
  102.              that a selected complex eigenvalue may no longer satisfy
  103.              SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may
  104.              change the value of complex eigenvalues (especially if the
  105.              eigenvalue is ill-conditioned); in this case INFO may be set to
  106.              N+3 (see INFO below).
  107.  
  108.      SENSE   (input) CHARACTER*1
  109.              Determines which reciprocal condition numbers are computed.  =
  110.              'N': None are computed;
  111.              = 'E': Computed for average of selected eigenvalues only;
  112.              = 'V': Computed for selected right invariant subspace only;
  113.              = 'B': Computed for both.  If SENSE = 'E', 'V' or 'B', SORT must
  114.              equal 'S'.
  115.  
  116.      N       (input) INTEGER
  117.              The order of the matrix A. N >= 0.
  118.  
  119.      A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)
  120.              On entry, the N-by-N matrix A.  On exit, A is overwritten by its
  121.              real Schur form T.
  122.  
  123.      LDA     (input) INTEGER
  124.              The leading dimension of the array A.  LDA >= max(1,N).
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      SDIM    (output) INTEGER
  141.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  142.              eigenvalues (after sorting) for which SELECT is true. (Complex
  143.              conjugate pairs for which SELECT is true for either eigenvalue
  144.              count as 2.)
  145.  
  146.      WR      (output) DOUBLE PRECISION array, dimension (N)
  147.              WI      (output) DOUBLE PRECISION array, dimension (N) WR and WI
  148.              contain the real and imaginary parts, respectively, of the
  149.              computed eigenvalues, in the same order that they appear on the
  150.              diagonal of the output Schur form T.  Complex conjugate pairs of
  151.              eigenvalues appear consecutively with the eigenvalue having the
  152.              positive imaginary part first.
  153.  
  154.      VS      (output) DOUBLE PRECISION array, dimension (LDVS,N)
  155.              If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur
  156.              vectors.  If JOBVS = 'N', VS is not referenced.
  157.  
  158.      LDVS    (input) INTEGER
  159.              The leading dimension of the array VS.  LDVS >= 1, and if JOBVS =
  160.              'V', LDVS >= N.
  161.  
  162.      RCONDE  (output) DOUBLE PRECISION
  163.              If SENSE = 'E' or 'B', RCONDE contains the reciprocal condition
  164.              number for the average of the selected eigenvalues.  Not
  165.              referenced if SENSE = 'N' or 'V'.
  166.  
  167.      RCONDV  (output) DOUBLE PRECISION
  168.              If SENSE = 'V' or 'B', RCONDV contains the reciprocal condition
  169.              number for the selected right invariant subspace.  Not referenced
  170.              if SENSE = 'N' or 'E'.
  171.  
  172.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  173.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  174.  
  175.      LWORK   (input) INTEGER
  176.              The dimension of the array WORK.  LWORK >= max(1,3*N).  Also, if
  177.              SENSE = 'E' or 'V' or 'B', LWORK >= N+2*SDIM*(N-SDIM), where SDIM
  178.              is the number of selected eigenvalues computed by this routine.
  179.              Note that N+2*SDIM*(N-SDIM) <= N+N*N/2.  For good performance,
  180.              LWORK must generally be larger.
  181.  
  182.      IWORK   (workspace/output) INTEGER array, dimension (LIWORK)
  183.              Not referenced if SENSE = 'N' or 'E'.  On exit, if INFO = 0,
  184.              IWORK(1) returns the optimal LIWORK.
  185.  
  186.      LIWORK  (input) INTEGER
  187.              The dimension of the array IWORK.  LIWORK >= 1; if SENSE = 'V' or
  188.              'B', LIWORK >= SDIM*(N-SDIM).
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEESSSSXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      BWORK   (workspace) LOGICAL array, dimension (N)
  207.              Not referenced if SORT = 'N'.
  208.  
  209.      INFO    (output) INTEGER
  210.              = 0: successful exit
  211.              < 0: if INFO = -i, the i-th argument had an illegal value.
  212.              > 0: if INFO = i, and i is
  213.              <= N: the QR algorithm failed to compute all the
  214.              eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain
  215.              those eigenvalues which have converged; if JOBVS = 'V', VS
  216.              contains the transformation which reduces A to its partially
  217.              converged Schur form.  = N+1: the eigenvalues could not be
  218.              reordered because some eigenvalues were too close to separate
  219.              (the problem is very ill-conditioned); = N+2: after reordering,
  220.              roundoff changed values of some complex eigenvalues so that
  221.              leading eigenvalues in the Schur form no longer satisfy
  222.              SELECT=.TRUE.  This could also be caused by underflow due to
  223.              scaling.
  224.  
  225. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  226.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  227.  
  228.      This man page is available only online.
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.